Tutorial: Using the API functionality of binary_c-python

This notebook shows how to use the API functions that interface with binary_c. It usually is better to use wrapper functions that internally use these API functions, because most of the output here is very raw

Binaryc-python uses the Python-C extension framework to interface Python with C. The sourcecode for this is contained in src/binary_c_python.c, and the functions are available via from binarycpython import _binary_c_bindings.

The following functions are available through the API: (run cell below)

[1]:

from binarycpython import _binary_c_bindings
help(_binary_c_bindings)

Help on module binarycpython._binary_c_bindings in binarycpython:

NAME
binarycpython._binary_c_bindings - Module to interface the Binary_c API with python.

FUNCTIONS
free_persistent_data_memaddr_and_return_json_output(...)
Frees the persistent_data memory and returns the json output.

Arguments:
store capsule: capsule containing the memory adress of the persistent data object (contains the ensemble)

free_store_memaddr(...)
Frees the store memaddr.

Arguments:
store capsule: capsule containing the memory adress of the store object

return_arglines(...)
Return the default args for a binary_c system

Arguments:
No arguments.

return_help(...)
Return the help info for a given parameter

Arguments:
parameter: parameter name.

return_help_all(...)
Return an overview of all the parameters, their description, categorized in sections

Arguments:
No arguments.

return_maximum_mass_ratio_for_RLOF(...)
Returns a string containing the maximum mass ratio for which a binary system does not RLOF at ZAMS. Please use the wrapper functions in utils for this except when you know what you're doing.

Arguments:
argstring: argument string for binary_c
(opt) store_capsule: capsule containing memory adress for the store object.unction. Default = Null

return_minimum_orbit_for_RLOF(...)
Returns a string containing the minimum orbit and separation for which a binary system does not RLOF at ZAMS. Please use the wrapper functions in utils for this except when you know what you're doing.

Arguments:
argstring: argument string for binary_c
(opt) store_capsule: capsule containing memory adress for the store object.unction. Default = Null

return_persistent_data_memaddr(...)
Return the store memory adress that will be passed to run_population

Arguments:
No arguments.

return_store_memaddr(...)
Return the store memory adress that will be passed to run_population

Arguments:
No arguments.

return_version_info(...)
Return the version information of the used binary_c build

Arguments:
No arguments.

run_system(...)
Function to run a system. This is a general function that will be able to handle different kinds of situations: single system run with different settings, population run with different settings, etc. To avoid having too many functions doing slightly different things.

Arguments:
argstring: argument string for binary_c
(opt) custom_logging_func_memaddr: memory address value for custom logging function. Default = -1 (None)
(opt) store_memaddr: memory adress of the store. Default = -1 (None)
(opt) write_logfile: Boolean (in int form) for whether to enable the writing of the log function. Default = 0
(opt) population: Boolean (in int form) for whether this system is part of a population run. Default = 0.

test_func(...)
Function that contains random snippets. Do not expect this to remain available, or reliable. i.e. dont use it.

FILE
/home/david/.pyenv/versions/3.9.9/envs/binarycpython3.9.9/lib/python3.9/site-packages/binarycpython/_binary_c_bindings.cpython-39-x86_64-linux-gnu.so

There are three main categories of functions:

Functions to get information from binary_c: these can be used to evolve systems, and get utility information from binary_c.
- run_system
- return_minimum_orbit_for_RLOF
- return_maximum_mass_ratio_for_RLOF
- return_help
- return_help_all
- return_arglines
Memory creation functions: these can be used to have binary_c allocate memory which is used or written to by binary_c
- return_persistent_data_memaddr
- return_store_memaddr
Memory freeing functions: These can be used to free the allocated memory, and in the case of persistent memory it will also return the contents of the ensemble
- free_persistent_data_memaddr_and_return_json_output
- free_store_memaddr

Example usage:

Setting up, using and freeing store

[2]:

# allocating store memory
store_memaddr = _binary_c_bindings.return_store_memaddr()
print(store_memaddr)

# Here we set up the argument string that is passed to the bindings
argstring = """
binary_c M_1 {M_1} orbital_period {orbital_period} eccentricity {eccentricity} metallicity {metallicity} max_evolution_time {max_evolution_time}
""".format(
    M_1=10,
    orbital_period=4500,
    eccentricity=0.0,
    metallicity=0.02,
    max_evolution_time=15000,
).strip()

#
output = _binary_c_bindings.run_system(argstring, store_memaddr=store_memaddr)
print(output)

# Free the store
_binary_c_bindings.free_store_memaddr(store_memaddr)

<capsule object "STORE" at 0x7f87e3369720>
SINGLE_STAR_LIFETIME 10 28.4838

Getting information from binary_c

We can get information for a parameter via return_help(parameter_name): This will return an unparsed output

[3]:

print(_binary_c_bindings.return_help('M_1'))

binary_c help for variable : M_1 <Float>

The initial mass of star one (in solar units, internally this is star index 0).

Default : 0
Random variation : log-spaced double between 0.1 and 100

We can get information on all available parameters via return_help(parameter_name):

[4]:

print('\n'.join(_binary_c_bindings.return_help_all().splitlines()[:10]))
print("(abridged)")


############################################################
##### Section Stars
############################################################
metallicity : This sets the metallicity of the stars, i.e. the amount (by mass) of matter which is not hydrogen or helium. If you are using the BSE algorithm, this must be 1e-4 <= metallicity <= 0.03. See also nucsyn_metallicity and effective_metallicity. : (null)
effective_metallicity : This sets effective metallicity of stars as used in routines like the Schneider wind loss. If not set, or set to DEFAULT_TO_METALLICITY (==-1, the default), this is just the same as metallicity. The main difference between effective_metallicity and metallicity is the range of validity: 0 <= effective_metallicity <= 1, while metallicity's range of validity is limited by the stellar evolution algorithm (so, for BSE, is 1e-4 <= metallicity <= 0.03). : (null)
M_1 : The initial mass of star one (in solar units, internally this is star index 0). : (null)
M_2 : The initial mass of star two (in solar units, internally this is star index 1). : (null)
M_3 : The initial mass of star three (in solar units, internally this is star index 2). : (null)
M_4 : The initial mass of star four (in solar units, internally this is star index 3). : (null)
(abridged)

We can get all the parameter names and their default values with return_arglines(): (abridged output)

[5]:

print('\n'.join(_binary_c_bindings.return_arglines().splitlines()[:4]))
print("(abridged)")

__ARG_BEGIN
defaults_set = 2022a
skip_bad_args = 0
metallicity = 0.02
(abridged)

Lastly, we can ask binary_c to determine the minimum period or maximum mass for RLOF at the ZAMS: Both of them need an argstring as input.

[6]:

store_memaddr = _binary_c_bindings.return_store_memaddr()
argstring = """
binary_c M_1 {M_1} orbital_period {orbital_period} eccentricity {eccentricity} metallicity {metallicity} max_evolution_time {max_evolution_time}
""".format(
    M_1=10,
    orbital_period=4500.0,
    eccentricity=0.0,
    metallicity=0.02,
    max_evolution_time=15000,
).strip()

output = _binary_c_bindings.return_minimum_orbit_for_RLOF(argstring, store_capsule=store_memaddr)
print(output)

MINIMUM SEPARATION 0.31
MINIMUM PERIOD 0.00632092